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PIV/HPIV Film Analysis Software Package 

Abstract 

A PIV/HPIV film analysis software system was developed that calculates the 2- 
dimentional spatial autocorrelations of subregions of Particle Image Velocimetry (PIV) or 
Holographic Particle Image Velocimetry (HPIV) film recordings. The software controls 
three hardware subsystems including 1) a Kodak Megaplus 1.4 camera and EPIX 4MEG 
framegrabber subsystem, 2) an IEEE/Unidex 1 1 precision motion control subsystem, and 
3) an Alacron i860 array processor subsystem. The software package runs on an IBM 
PC/AT host computer working either under Microsoft Windows v3.1 or Windows 95 
operating systems. It is capable of processing five PIV or HPIV displacement vectors per 
second, and is completely automated with the exception of user input to a configuration 
file prior to analysis execution for update of various system parameters. 
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PIV/HPIV Film Analysis Software Package 


1.0 Introduction 


The IBM PC/AT PIV/HPIV film analysis software system calculates the 2- 
dimentional spatial autocorrelations of subregions of PIV or HPIV film recordings using 
the Alacron i860 array processor subsystem. It runs on an IBM PC/AT host computer 
working either under Microsoft Windows v3.1 or Windows 95 operating systems. The 
system is capable of processing five displacement vectors per second, and is completely 
automated with the exception of user input to a configuration file prior to analysis 
execution for update of various system parameters. The executable program file is named 
PIV54.exe with a configuration text file calledKODAK54.cfg. 

2.0 Hardware and Software Interface Description 

The hardware used in the analysis system includes three basic subsystems. They 
include 1) the Kodak Megaplus vl.4 digital camera and Epix frame grabber 4MEG video 
subsystem for transfer of the individual subregion areas to PC memory, 2) the National 
Instruments IEEE/GPIB NI-488.2 interface card and Aerotech Unidex 1 1 precision motion 
control subsystem for transfer of the film frame to the adjacent image correlation regions, 
and 3) the Alacron FT200-AT array processor subsystem for calculating the 128x128 2- 
dimensional autocorrelation of the image subregion. The hardware and software versions 
used in the software development for each subsystem include: 

DATE 

1) Kodak Megaplus Digital Camera System vl.4 1992 

Epix Framegrabber Object Library m4obm7wl.lib vl .7 1992 

Epix Framegrabber Image Processing Library pxipm7wl.lib vl.7 1992 

2) IEEE/GPIB NI-488.2 interface card 1992 

IEEE/GPIB NI-488.2 function Library gpib.lib v2.1.1 1992 

Aerotech Unidex 1 1 Motion Controller 1988 

3) Alacron FT200- AT array processor board 1995 

Alacron FT200-AT RT860 Slave Mode Library w3slv860.1ib vl.7 1995 
Portland Group Compiler package v2.3 1995 
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3.0 Software Description 


General Software Description 


The software is modular in nature and applies the various hardware and software 
control functions in a sequential manner. The order of program execution typically 
involves the following steps: 


1) system initialization 

2) read in configuration file parameters 

3) initialize the i860 array processor and load i860 program 

4) calculate the FFT weight functions on the i860 

5) initialize the IEEE/GPIB and Unidex 1 1 systems 

6) initialize the EPIX framegrabber and Kodak Megaplus systems 

7) send analysis parameters to i860 

8) move Unidex system to start position and zero coordinates 

9) Begin main analysis loop which involves: 

a) capture subimage using framegrabber 

b) transfer position information to i860 

c) transfer image data to i860 

d) move Unidex to next analysis subregion 

e) calculate the 2-d autocorrelation of the 54 subimages which involves: 

l. ) compute and apply active threshold on raw image data 
II.) check for totally white or black image field 

m. ) apply default peak values 

IV. ) calculate forward 2d fft 

V. ) autocorrelate the 2d fft field 
VT.) center the final correlation field 
VII.) calculate the inverse 2d fft 
VUI.) zero out DC peak region 

IX. ) scale output correlation field to 0-255 

X. ) apply search box thresholding 

XI. ) calculate the top three centroid positions 

XII. ) write the results to output file 

f) retrieve the final correlation number 54 and display on monitor 

10) return Unidex 1 1 to zero position 

11) free up memory and close hardware 
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The user provides various analysis parameters through the kodak54.cfg 
configuration file. Image and correlation field threshold levels, Unidex shift amounts and 
sizes, DC peak extent, file output name, magnification levels, laser pulse separation level, 
Kodak camera exposure level, correlation field search box extents, and default peak 
positions are required. Once the configuration parameters are setup, the program is 
executed using the user parameters provided. Analysis at this point is automated, with 
interaction with the user limited to display of the current analysis position on the computer 
screen, and display of the most recent correlation field on the RSI 70 monitor. An update 
of the approximate time remaining in the analysis is also provided. The top three centroid 
positions and relative intensity levels are written out for each analyzed position in the 
image field in ASCII text format. 

3.2 Detailed Software Description 

The program is made up of three ‘c’ source files, and three resource files. The 
program is of a Windows ‘quickwin’ type which allows it to be run in Windows 3.1 or 
Windows 95, but allows minimal user interaction. Interaction and control of various 
program execution parameters is provided by a configuration file as described in the 
previous sections. The user edits the configuration file before program execution, and 
when the program is run, the configuration parameters are read in from that file. The 
program then displays the parameters on the monitor in a quickwin window and begins the 
analysis with no further user input. 

The source file PIV54c.C is the primary ‘control’ program, and the source file 
PIV54p.C is a ‘slave’ program run on the i860 array processor. Each of these will be 
detailed in the following section. The source file PIV54w.C develops and displays the 
quickwin window and will not be detailed here. The user is referred to the commented 
listing provided. The three additional resource files will also not be detailed here. 

The source file PIV54c.C contains seven modular functions that perform the 
various initialization operations for the system. The main() function begins and ends 
program execution and performs memory allocation, initialization, and control 
functionality. Its first task is to call the read_config() function which reads the 
configuration file parameters into global variables for use later in the program. The main() 
function then continues on and prints the configuration parameters in the quickwin 
windows, followed by data array memory allocation calls. 

The Alacron i860 array processor board is then initialized and opened with the 
functions alopenQ and aldevQ, respectively. The i860 slave program ‘piv54p’ is then 
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loaded into i860 memory using the function almapload(). Memory is then initialized and 
allocated using the function i860malloc() and malloc() functions. A call to the i860 slave 
function dowts() is then made using the master function alcall(). This function calculates 
the FFT weight functions needed for the autocorrelation routine. The function alwait() 
prevents further program execution until the alcall() function returns from the i860. 

The IEEE/Unidex 1 1 system is then initialized using the ibfind(), ibdev(), ibclr(), 
and ibconfig() functions. The EPIX 4MEG video framegrabber and Kodak Megaplus 
systems are then initialized and opened using the do_open() and pxd_m4open() functions. 
An initialization image is then captured using the pxd_videkset() and pxd_videkdo() 
functions. 

The correlation analysis parameter set is then sent to the i860 using the functions 
alsetla() and alsetba() functions. This includes 12 long integer values and a character 
string containing the output filename. A master call to alcall() and alwait(), in turn, calls 
the i860 slave function filetransfer() which reassembles the filename from individual 
characters into a character string name for the file. 

The IEEE/Unidex system is then positioned to its initial analysis system position 
using the functions ibrsp() and ibwrtQ. The main analysis looping sequence is then begun, 
which involves: 

1) capturing a low resolution Kodak Megaplus image of a subregion in the film, 

2) transferring the image data to the i860 memory, 

3) performing the autocorrelation of the image in 128x128 sections, 

4) finding the centroids of the top three correlation peaks, 

5) writing the results out to file, 

6) and moving the film to the next position for the process to repeat. 

The low resolution image capture is performed with the pxd_videkdo() and 
pxd_video() functions. The camera exposure level for the pxd_videkdo() function was 
provided by the user in the configuration file. The pxd_video() function controls the 
digitize/display/blank control functionality of the framegrabber and is set to image 
blanking to speed up processing here. Image data is sent from the framegrabber to PC 
memory, and then from the PC memory to the i860 memory in a piece-wise manner, based 
on the fact that the EPIX function pxd_io() and Alacron function alsetba() are limited to 
transferring 32000 bytes of information at a time. This requires the transfer of image data 
in nine pieces 50 rows by 640 pixels long. Image transfer from the framegrabber buffer to 
the PC memory is accomplished with the buf_to_array() function, which in turn calls the 
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EPIX functions pxd_iopen() and pxd_io(). Transfer from the PC memory to i860 memory 
is then done with the Alacron alsetba() function. A call to the i860 slave function 
transfer() is then required to reassemble the image field to a full 640x448 from its nine 
transferred pieces. 

Once the image and analysis parameter set has been sent to i860 memory, the i860 
slave function dofft() is called. This function breaks up the image into 54 128x128 
subimage regions, and perform the autocorrelations of each. The 54 subimage regions 
represent a 9x6 grid of adjacent regions in the full 640x448 image field. Each subimage is 
128x128 pixels and 50% oversampling of the data results in an x, and a y, shift of 64 
pixels in each direction between adjacent subimage region. This ultimately results in 9 
available 128x128 images in the x direction (out of 640 image pixels in that direction), and 
6 available images in the y direction (out of 448 image pixels in that direction), which 
finally results in 54 autocorrelations for each captured image field in the analysis. 

The autocorrelation process begins with a determination of the weighted mean 
pixel level for the 128x128 subimage region being evaluated: 


Weighted Mean = 


i' =l 28,7=1 28 

( Weigh, 

1 = 0 ,) =0 

_____ 


where 7 is the 8-bit pixel intensities (0-255), and weight is the user input weighting amount 
usually set to between 0.65 and 1.25. If a pixel value is found to be greater than the 
weighted mean value it is set to zero, and if found less than or equal to the weighted mean 
value it is set to its compliment value. This produces an image field of bright white 
particle image dots on a black background. 

A count of bright and dark levels in the current image field is kept so that if 
excessive bright or dark areas are present the frame can be zeroed out for easier data 
validation efforts later. This condition typically occurs in boundary regions, image flair 
regions, or non-seeded regions. On a similar theme, a default correlation peak set is 
introduced into the image field to aid in data validation efforts later. This is done by 
setting a series of six pixels to a intensity level of 20 corresponding to a set of three 
particle image pairs that will correlate if the entire image field is black. The user elects to 
introduce these default peaks and chooses their relative locations. The minimal 20 pixel 
intensity level causes no adverse affects on a legitimate PIV image field, which has particle 
image peak intensities near 255 and contrast levels in excess of 50: 1 . 
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Following the active threshold (weighted mean) implementation, the forward 2- 
dimensional Fourier transform is applied to the data set using the Alacron provided 
function cfft2d(). The 2d FFT is then autocorrelated with itself: 

3[*(a,J0)] = 3 [f\x,y) ® f(x,y )] = \F(p,qf 

which basically reduces to squaring the real and imaginary parts of the FFT and adding 
them together: 

\F(p,qf = A f ( p,q)e i(px+qy) X A F (p,q)e^ px+tiy) = {Re[F(p^)]} 2 + {Im [F(p,q)]} 2 

where F(p,q) is the complex 2d forward FFT of the image field. The correlated image 
field is then centered in the image field by taking advantage of the translation property of 
the Fourier transform which sets the origin of the Fourier transform of f(x,y) to the center 
of its corresponding NxN frequency square by multiplying f(x,y) by (- l*f y . This is coded 
up by multiplying the x and y frequency components values of f(x) and f(y) by (-f)and 
(-l) y respectively. Mathematically, this is represented by: 

/(jc,y)(-l)* +> o F(u-N I2,v-N 12) 

The inverse Fourier transform is then obtained to produce the desired PIV 
autocorrelation pattern, which takes the form of a self-correlation peak centered in the 
image field, and symmetric satellite correlation peaks about the center of the image field 
representing the average particle image displacement present in the field. 

Following the successful completing of the autocorrelation processing st$)s, a 
determination of the locations of the satellite peaks needs to be conducted. This first 
involves applying a filter to the self correlation peak centered in the image field. The DC 
peak extent value provided by the user is used to zero-out values extending from the 
center of the image field out to the peak extent level. This basically zeroes out a square 
box pattern centered around pixels (64,64). The correlation field is then scaled to 8-bit 
levels (0-255) for display and storage later. This involves calculating the minimum and 
maximum pixel intensity values in the image field and applying: 

„ , , , _ . Pixel Intensity + (—1.0* Minimum) „„ 

Scaled Pixel Intensity = — x 255 

Maximum + (-1.0* Minimum ) 
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The user supplied search box values are then used to apply a hard threshold level within 
the search box boundaries. An additional 0-255 scaling operation is done before the hard 
threshold to enhance the dynamic range levels within the search box. The hard threshold 
level is then applied so that if the pixel value is less than the user threshold it is zeroed. 

A custom set of image centroid functions are then applied to the search box 
region. This begins by calling the i860 slave function main_search() from within the 
dofft() function. A series of three dynamic centroid storage arrays are used to store 
potential centroid values, of which the top three intensity levels will be saved away. The 
main_search() function checks the pixel intensity levels from the top left portion of the 
search box to the bottom right, and calls blob_search() if it finds a pixel above the 
threshold level. The blob_search() function in turn looks for connected neighbors that are 
above the threshold level and stores away the (x,y) positions and the intensity value for 
each pixel associated with a given blob. Once the entire blob extent has been determined, 
its centroid is evaluated using the i860 slave function find_centroid() which uses a 
weighted mean average routine to determine the x, y, and intensity levels of the blob. A 
comparison of its weighted mean intensity level is then made with the top three centroids, 
and if it beats any of the three, it is placed ahead of them in the final centroid arrays. 

Returning to the main_search() function, and following the determination of the 
top three centroid positions within the search box, the centroid x and y positions are 
scaled relative to the center of the image field, to give the relative displacement away from 
the self-correlation peak (which is the average displacement of the particle pairs in the 
field). The magnification and laser pulse separation are then taken into account using the 
user defined values to transform the final centroid pixel displacements to velocity 
according to: 


Velocity Level = 


( Pixel Displacement Level )*( Analysis Scale Factor ) 

( Acuisition Magnification Level)*( Laser Pulse Separation ) 


where the analysis scale factor, acquisition magnification level, and laser pulse separation 
are determined by, and supplied by the user. The x and y position is also scaled at this 
point in the program according to: 


Scaled Position r v 


[ Position x *( Analysis Scale Factor )] 
( Acquisition Magnification Level ) 


+ ( Unidex Shift Amount) 


where the (Unidex Shift Amount),, y represents the amount of x or y shift between image 
capture frames applied by the Unidex film translation system. 
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The top three autocorrelation centroid positions are then written out to file along 
with the 8-bit (0-255) correlation peak intensity level, and the x and y position. The output 
file format takes the following form of eleven columns of data across: 


column 1 column! cojumn3 column4 column? column6 column7 columns column9 cohimnlO column 11 
x position y position 1* u l rt v l rt peak 2 nd u 2 nd v 2 nd peak 3 rd u 3 rt v 3 rd peak 

where u and v are the u and v velocity components, respectively, and peak is the relative 
centroid correlation peak height recorded during the analysis process. The 1 st , 2 nd , and 3 rd 
designations represent the strongest, 2 nd strongest, and 3 rd strongest correlation peak 
heights, respectively. 

Following the autocorrelation analysis and data write-out to file for a single captured 
(640x448) image field, the program returns to the master program’s control and the main() 
function. The next image position (defined by the Unidex film translation away from the 
previous adjacent position) is then captured, transferred to i860 array memory, and analyzed 
in an identical way. This process continues until the entire film frame is analyzed, which is 
defined by the number of Unidex film x/y translations provided by the user. 

Following the analysis of the entire film frame, the Unidex is repositioned at the 
original (0,0) position. Memory is also freed up, and hardware/output data files are closed. 

4.0 Analysis Procedures 

The basic analyst process includes three steps which include 1) aligning the film in 
the film holder, 2) setting up the configuration file, and 3) running the analysis program. 
Each of these will be detailed in this section of the document. Some additional preliminary 
analysis setup procedures are also required before analysis can commence, but will not be 
covered. They include 1) determination of acquisition and analysis magnification levels, 2) 
determination of an adequate registration point on each film frame, 3) determination of 
Unidex x and y shift amounts, 4) determination of the number of Unidex x and y shifts to 
cover the entire film frame, and 5) determination of the origin (0,0) position to begin each 
analysis. (NOTE: the starting position of the analysis should be the top- and left-most 
position of the data field, in that positive motion increments of the Unidex system will move 
the film field-of-view to the right and downward). 

The first step in the analysis procedure involves loading the film in the film holder 
properly. This basically involves three steps. First, the film must be loaded in the film 
holder and aligned so that the horizontal and vertical film positions are lined up accurately 
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with the Unidex motion directions. This is typically done using the front panel controls of 
the Unidex control box is slew mode, and using the edges of the film frame field or other 
horizontal and vertical lines on the film, to line up the field with the Unidex motion. Once 
this first step is done, the film is repositioned at a user defined registration point on the film. 
The Unidex control box is again used here to move the film to this position. The Unidex 
system is then zeroed out at this registration point. The film must finally be positioned at 
the film analysis start position by moving a predetermined amount away from the 
registration point in both the x and y directions. This is typically in the extreme upper left 
comer of the film frame’s field of view, so that positive x/y Unidex motion results in film 
motion to the right and downward. The Unidex control box is again used to move this 
predetermined amount using jog/step instead of slew control. The Unidex system is again 
zeroed out, so that this position acts as the analysis origin (0,0) position. IEEE computer 
communication control of the Unidex system is then enabled. 

The second analysis step involves setting up the configuration file KODAK54.CFG. 
An example configuration file input is provided below: 


SoftwareJVersion_Number 

1.2 

Camera_Exposure„Level(ms) 

90 

#steps_Xdimension 

10 

#steps_Ydimension 

15 

Image_Active JThreshold_Scale(0.65- 1 .25) 

1.0 

FP_DC„Peak_Extent(l-20 pixels) 

10 

Search_Box_Xmin(0*128 pixels) 

35 

Search_Box_Xmax(0- 1 28 pixels) 

79 

Search_Box_Ymin(0-128 pixels) 

10 

Search_Box_Ymax(0-128 pixels) 

39 

Default_Peak_Xpos(0-64 pixels) 

0 

Default_Peak_Ypos(0-64 pixels) 

38 

Centroid_ThreshoId_Level(0-255) 

250 

Analysis_Pixel_Scale_Factor(p m/pixel) 

10.0628 

Acquisition_Magnification 

0.93066 

Laser„Pulse_Separation(microsec) 

0.60000 

Unidex_Xshift_Amount(microns) 

5796 

Unidex_Y shift_Amount(microns) 

-3864 

Output_Datafile_Name 

f71r7.dat 


PIV analysis system configuration file: KODAK54.CFG 


The file supplies various analysis system parameters needed for processing. The 
user provides four basic types of information. First, the user must provide various setup 
parameters such as acquisition magnification, analysis magnification, and laser pulse 
separation timing. Second, the user must provide Unidex film positioning and motion 
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information including the amount of x/y shift in each direction, and the number of shifts. 
The third type of information includes autocorrelation analysis parameters. These are 
determined on a trial by error basis using test correlations and varying the parameters to 
enhance and maximize the correlation image fields SNR. The exposure level of the Kodak 
Megaplus camera (in milliseconds) needs to be determined first, where test correlations 
are used at various exposure levels to optimize the exposure level for a typical frame on a 
given roll. Image and centroid threshold levels are also evaluated with respect to test 
correlations. The image threshold factor applies a threshold to the raw image before FFT 
processing based on the average pixel intensity (weighted mean) in the image. The 
centroid threshold level limits the centroid search to pixel intensity values above a certain 
level. The self-correlation peak extent also needs to be determined in pixel units based on 
an evaluation of its radial extent out from the correlation image center. Correlation search 
box limits also need to be set, allowing for movement of the correlation peak at various 
positions across the field. And finally, a default peak correlation position can be inserted 
in the event of a totally black or totally white image field. 

Once the configuration file is properly setup, it is saved away, and the analysis system 
program is run. This process starts the automated autocorrelation analysis routine that 
moves the film in a stepwise manner, and analyzes 54 correlation subregions for each 
translation position in the flow. The analysis parameters that were read in from the 
configuration file are displayed in the ‘quickwin’ box supplied by the program, and an 
approximate time period remaining in the processing. The system is currently capable of 5 
vector correlations per second, which translates to approximately 30-40 minutes of analysis 
time for a standard 70 mm film frame 

5.0 Software Development Issues 


The PrV/HPIV film analysis software was written in a Microsoft ‘quickwin’ 
format, which allows the program to be run in Windows 3.1 or Windows 95, but which 
doesn’t allow any user interaction with the program while it is running. Five separate files 
are required during the compile and link process: 


1) Piv54c.c - 

2) Piv54p.c - 

3) Piv54w.c - 

4) Piv54.def - 

5) Piv54.rc 


The analysis program’s ‘master’ control source file 
The analysis program’s i860 ‘slave’ soiree file 
The quickwin source file 
The definition file for the program 
The resource file for the program 
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6) Piv54.ico - 


The bitmap icon for the program 


In addition, a command line batch file has been used to control the compile, link, 
and resource compiler stages of the build process. This files name is Piv54.bat. The 
program was compiled with Microsoft C compiler version v8.00, linker version v5.5, and 
resource compiler v3.1 1. 

Editing of the code to add new functionality, or to change existing capabilities is 
relatively straight forward. The modular nature of the code allows this. The quickwin 
source file Piv54w.c, definition file Piv54.def, resource file Piv54.rc, and icon file 
Piv54.ico should not require any changes and should be left alone if possible. 

A copy of the compile/link batch file listing is provided below: 


pgcc -Mreentrant *o piv54p piv54p.c i8601ib.a pgcnl.a libm.a 
cl -c -AL -Gsw -Zpe -DC_MSC -Dmain=Cmain piv54c.c plv54w.c 

link /NOD /NOE piv54c+piv54w,„w3slv860 libw Llibcew m4obM7WL pxipMTWL gpib,piv54.def 
rc -K piv54.rc piv54c.exe 


It calls the Portland Group Compiler for compiling on the i860 processor board, and the 
Microsoft compiler, linker, and resource compiler, with various switches setup for a 
quickwin application. 

This software package was developed under contract to NASA. Requests for 
copies of the source and executable codes described in this report should be directed in 
writing to one of the following: 

NASA Langley Research Center 
Technology Applications Group 
Mail Stop 118 

Hampton, Virginia 23681-0001 


or 


Vigyan, Inc. 

Aeronautical Research Group 
30 Research Drive 
Hampton, Virginia 23666-1325 
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